package com.sqlcheck.service;

import com.sqlcheck.dto.git.GitProjectInfo;
import com.sqlcheck.dto.git.GitRepositoryInfo;
import com.sqlcheck.enums.GitPlatform;

import java.util.List;

/**
 * Git平台通用API服务接口
 * 支持GitLab、Gitee、GitHub等多个Git平台
 */
public interface GitApiService {

    /**
     * 获取支持的Git平台
     */
    GitPlatform getSupportedPlatform();

    /**
     * 获取用户的项目列表
     *
     * @param accessToken 访问令牌
     * @param page        页码
     * @param perPage     每页数量
     * @return 项目列表
     */
    List<GitProjectInfo> getUserProjects(String accessToken, int page, int perPage);

    /**
     * 根据项目URL获取项目信息
     * 
     * @param accessToken 访问令牌
     * @param projectUrl  项目URL
     * @return 项目信息
     */
    GitProjectInfo getProjectByUrl(String accessToken, String projectUrl);

    /**
     * 获取仓库信息
     * 
     * @param accessToken 访问令牌
     * @param projectId   项目ID（对于GitLab）或owner/repo格式（对于GitHub/Gitee）
     * @return 仓库信息
     */
    GitRepositoryInfo getRepositoryInfo(String accessToken, String projectId);

    /**
     * 验证项目访问权限
     * 
     * @param accessToken 访问令牌
     * @param projectUrl  项目URL
     * @return 是否有访问权限
     */
    boolean validateProjectAccess(String accessToken, String projectUrl);

    /**
     * 获取项目默认分支
     * 
     * @param accessToken 访问令牌
     * @param projectId   项目ID
     * @return 默认分支名
     */
    String getDefaultBranch(String accessToken, String projectId);

    /**
     * 获取项目分支列表
     * 
     * @param accessToken 访问令牌
     * @param projectId   项目ID
     * @return 分支列表
     */
    List<String> getProjectBranches(String accessToken, String projectId);

    /**
     * 从项目URL中提取项目标识
     * 
     * @param projectUrl 项目URL
     * @return 项目标识（GitLab为path，GitHub/Gitee为owner/repo）
     */
    String extractProjectIdentifier(String projectUrl);

    /**
     * 构建HTTP克隆URL
     * 
     * @param projectUrl  项目URL
     * @param accessToken 访问令牌
     * @return 带认证的克隆URL
     */
    String buildCloneUrl(String projectUrl, String accessToken);
}